About OpenTrials

From OpenTrials page: OpenTrials is a collaboration between Open Knowledge International and Dr Ben Goldacre from the University of Oxford DataLab. It aims to locate, match, and share all publicly accessible data and documents, on all trials conducted, on all medicines and other treatments, globally.

In addition to web search, the OpenTrials database is also accessible via API, documented as Open API (Swagger) format.

This short tutorial shows how to use this API from R with rapiclient.

Issues

Report rapiclient bugs on rapiclient issues. Source R Markdown for this page is here.

Report errors with OpenTrials data (for example, if a trial has incorrect treatments tagged to it) on this page.

Preparation

Install rapiclient from Github:

devtools::install_github("bergant/rapiclient")

Use get_api and get_operations to create R client functions:

library(rapiclient)
open_trials_api <- get_api("http://api.opentrials.net/v1/swagger.yaml")
open_trials_schemas <- get_schemas(open_trials_api)
open_trials <- get_operations(open_trials_api, handle_response = content_or_stop)

names(open_trials)

##  [1] "searchTrials"        "autocomplete"        "searchFDADocuments" 
##  [4] "getTrial"            "getPublication"      "getCondition"       
##  [7] "getOrganisation"     "getRecords"          "getRecord"          
## [10] "getPerson"           "getIntervention"     "list"               
## [13] "listFDAApplications" "getFDAApplication"   "listDocuments"      
## [16] "getDocument"

Search Trials

searchTrials returns trials based on a search query. By default, it’ll search in all of a trial’s attributes. Parameter q is a ElasticSearch query string. Parameters page (1 to 100) and per_page (10 to 100) are optional.

trials <- open_trials$searchTrials(q='public_title:(depressive OR depression)')

trials$total_count

## [1] 4050

length(trials$items)

## [1] 20

There are 4050 trials matching this search query and the first 20 already waiting in the trials$items list.

Take a look at the richness of the trial search result schema before using the results:

library(DiagrammeR)
grViz(
  rapiclient::get_schema_graphviz_dot(
    open_trials_api, 
    open_trials_api$definitions$TrialSearchResults
  ) 
)

Print some of the trial attributes in a table:

library(dplyr)
library(knitr)

lapply(trials$items, function(x) { data.frame(
    title = gsub("\n","",x$public_title), 
    source_id = x$source_id,
    sample_size = ifelse(length(x$target_sample_size)==0, NA, x$target_sample_size),
    status = x$status,
    registered = format(as.POSIXct(x$registration_date)),
    publications = length(x$publications),
    stringsAsFactors = FALSE
)}) %>% 
  bind_rows %>% 
  arrange(desc(sample_size)) %>% 
  kable(caption = "Table: some data from trials search result")

Table: some data from trials search result
title	source_id	sample_size	status	registered
Long-term Safety Study of Rapastinel as Adjunctive Therapy in Patients With Major Depressive Disorder	nct	500	ongoing	2016-12-21
Mental Health in Adults and Children- Frugal Innovations (MAC-FI): Adult Depression Component	nct	256	ongoing	2016-12-20
Reducing Fetal Exposure to Maternal Depression to Improve Infant Risk Mechanisms	nct	240	ongoing	2017-01-04
Conventional Bilateral rTMS vs. Bilateral Theta Burst Stimulation for Late-Life Depression	nct	220	ongoing	2016-12-16
Preeclampsia Research on Vitamin D, Inflammation, & Depression	nct	200	ongoing	2016-12-08
Study to Evaluate the Efficacy and Safety of Adjunctive Pimavanserin in Major Depressive Disorder (CLARITY)	nct	188	ongoing	2017-01-10
Stepped Care for Depression in Heart Failure	nct	180	ongoing	2016-12-15
Mantra Meditation in Major Depression	nct	130	ongoing	2016-12-14
Interpersonal Counseling (IPC) for Treatment of Depression in Adolescents	nct	120	ongoing	2016-12-20
Efficacy of H7-Coil DTMS Compared to H1-Coil DTMS in Subjects With Major Depression Disorder (MDD)	nct	105	ongoing	2017-01-05
Dynamics of Inflammation and Its Blockade on Motivational Circuitry in Depression	nct	80	ongoing	2016-12-28
Brief CBT for the Treatment of Depression During Inpatient Hospitalization	nct	75	ongoing	2017-01-04
A Study to Evaluate SAGE-217 in Subjects With Moderate to Severe Major Depressive Disorder	nct	62	ongoing	2016-12-14
Serum Cortisol Levels in Patients With Anxiety and Depression With Symptomatic Oral Lichen Planus	nct	60	ongoing	2017-01-04
Are Bright Lights and Regulated Sleep Effective Treatment for Depression?	nct	60	ongoing	2017-01-03
Effects of Online Cognitive Control Training on Rumination and Depressive Symptoms	nct	52	ongoing	2016-12-19
Emotional Awareness and SElf-regulation for Depression in Patients With Hypertension (EASE) Study	nct	48	ongoing	2017-01-05
CSE v. Epidural for Postpartum Depression	nct	46	ongoing	2017-01-11
Integrating HIV and Depression Self-Care to Improve Adherence in Perinatal Women	nct	40	ongoing	2017-01-06
The Experience of Older Adults Facing Depression for the First Time in Old Age	nct	15	ongoing	2016-12-23

Tips & Tricks

Print a function to see its documentation. For example:

open_trials$getTrial

## getTrial 
##  
## Description:
##    Returns a trial's details and related entities (e.g. `conditions`). 
## 
## Parameters:
##   id (string)
##     ID of the trial

If parameter name is a reserved word in R, quote it with backticks:

conditions <- 
  open_trials$autocomplete(`in` = "condition", q = "depression depressive", per_page = 100) %>% 
  getElement("items") %>% 
  bind_rows %>%  
  select(id, name)

Note that operations are not vectorised. You have to use the *apply functions to get the data for arguments with length > 1. For example, count the trials for each condition:

conditions$trials <- 
  sapply(conditions$id, function(x) {
    open_trials$searchTrials(q = sprintf("conditions.id:(%s)", x))[["total_count"]] 
  })  

conditions %>% arrange(desc(trials)) %>% top_n(30, wt = trials) %>% knitr::kable(.)

id	name	trials
0188f4f0-10b1-44f2-b949-c95bee23b4e4	F32.9 - Depressive episode, unspecified	4
004267e9-a20b-49d2-8d73-4313ce59db78	Topic: Mental Health Research Network, Primary Care Research Network for England; Subtopic: Depression, Not Assigned; Disease: Depression, All Diseases	4
016ae19a-8c44-11e6-be70-0242ac12000f	Mental Depression	2
01008ccb-c73d-4f15-8c10-2cb7ec1c65c9	Late Life Depression (LLD)	1
005a7e4e-b74d-4e96-a685-317923dab7c8	Depression Anxiety Sleep disturbances Circadian disturbances	1
00ae9a73-58f0-4871-b704-8399ffa79449	Major depressive disorder (episode or recurrent), moderately severe as principal DSM-IV diagnosis	1
00a154f8-8c6f-11e6-be70-0242ac12000f	Moderate to severe, or mild persistent, episode of Major Depression (DSM-IV) who initiate a new antidepressant treatment episode	1

OpenTrials Operations

From Swagger definition (“http://api.opentrials.net/v1/swagger.yaml”)

searchTrials

Description: Returns trials based on a search query. By default, it’ll search in all of a trial’s attributes. - q is a ElasticSearch query string (e.g. public_title:(depressive OR depression)) - page can take a value between 1 and 100 - per_page can take a value between 10 and 100

autocomplete

Description: Autocomplete search feature for supported database entities (condition, intervention, location, person, organisation). It has the same options as a regular search operation, with an extra required in parameter indicating the entity type to search.

searchFDADocuments

Description: Search the FDA documents

getTrial

Description: Returns a trial’s details and related entities (e.g. conditions).

getPublication

Description: Returns publication details

getCondition

Description: Returns condition details

getOrganisation

Description: Returns organisation details

getRecords

Description: Returns a trial’s raw records from its sources

getRecord

Description: Returns a trial’s raw record from its sources

getPerson

Description: Returns person details

getIntervention

Description: Returns intervention details

list

Description: Returns list of sources

listFDAApplications

Description: Returns FDA applications

getFDAApplication

Description: Returns an FDA application details

listDocuments

Description: Returns documents

getDocument

Description: Returns details of a document

List of Data Sources

OpenTrials data sources:

sources <- open_trials$list()
knitr::kable(bind_rows(sources), caption = "Table of sources")

Table of sources
id	name	source_url	type	terms_and_conditions_url
fda	U.S. Food and Drug Administration	http://www.fda.gov	other	NA
cochrane_schizophrenia	Cochrane Schizophrenia Group	http://schizophrenia.cochrane.org/	other	NA
euctr	EU Clinical Trials Register	https://www.clinicaltrialsregister.eu	register	https://www.clinicaltrialsregister.eu/disclaimer.html
nct	ClinicalTrials.gov	https://clinicaltrials.gov	register	https://clinicaltrials.gov/ct2/about-site/terms-conditions
hra	Health Research Authority	http://www.hra.nhs.uk	other	http://www.hra.nhs.uk/terms-conditions/
ictrp	WHO ICTRP	http://www.who.int/trialsearch/	register	http://www.who.int/ictrp/search/download/en/
fdadl	FDA Drug Labels	https://open.fda.gov	other	https://open.fda.gov/terms/
icdcm	ICD-CM	https://www.cms.gov/Medicare/Coding/ICD10/index.html	other	NA
icdpcs	ICD-PCS	https://www.cms.gov/Medicare/Coding/ICD10/index.html	other	NA
pubmed	PubMed	http://www.ncbi.nlm.nih.gov/pubmed	other	https://www.ncbi.nlm.nih.gov/home/about/policies.shtml

Other R Packages

Attached packages:

Xie Y (2016). knitr: A General-Purpose Package for Dynamic Report Generation in R. R package version 1.15.1, http://yihui.name/knitr/.

Wickham H and Francois R (2016). dplyr: A Grammar of Data Manipulation. R package version 0.5.0, https://CRAN.R-project.org/package=dplyr.

Sveidqvist K, Bostock M, Pettitt C, Daines M, Kashcha A and Iannone R (2017). DiagrammeR: Create Graph Diagrams and Flowcharts Using R. R package version 0.9.0, https://CRAN.R-project.org/package=DiagrammeR.

Other loaded packages in R session

Using OpenTrials API with R

Darko Bergant

2016-10-14, updated: 2017-02-13